<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">

<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Fika Documentation</title>
	
  <script type="text/javascript" src="lib/jquery.js"></script>
  <script type="text/javascript" src="lib/fika-docs.js"></script>
	<link rel="stylesheet" type="text/css" href="fika.css" />
</head>
<body>

<div class="back-link float-right">
  <a class="external" target="_top" href="../index.html">Back</a>
</div>

<h1>Fika Documentation</h1>

<div id="nav">
  <a class="initial-item" href="#intro">Intro</a> |
  <a href="#shell">Shell</a> |
  <a href="#core-library">Core Library</a> |
  <a href="#combinators">Combinators</a> |
  <a href="#history">History</a> |
  <a href="#dev">Development</a>
</div>

<div id="sections">

  <div id="intro">
    <h2>Introduction</h2>
    
    <h3>Names &amp; Numbers</h3>
    
    <p>
      Create a new name, 'add' to add two numbers:<br />
      <span class="code">add = +</span>
    </p>
  </div>

  <div id="shell">
    <h2>Shell</h2>
    Toggle stack tracing: <span class="code">:trace</span><br />
    Clear the output window: <span class="code">:clear</span><br />
    Show all defined names: <span class="code">:names</span><br />    
  </div>
  
  <div id="core-library">
    <h2>Core Library</h2>
    
    These operations are available when the Fika Shell is first loaded.
    
    <h3>Math Operations</h3>
    Add: <span class="code">+</span><br />
    Subtract: <span class="code">-</span><br />
    Multiply: <span class="code">*</span><br />
    Divide: <span class="code">/</span><br />
    
    <h3>Comparison Operations</h3>
    Equal: <span class="code">eq</span><br />    
    Less than: <span class="code">&lt;</span><br />
    Greater than: <span class="code">&gt;</span><br />
    Less than or equal: <span class="code">&lt;=</span><br />
    Greater than or equal: <span class="code">&gt;=</span><br />
    
    <h3>Making Decisions</h3>
    If, then, else: <span class="code">ifte</span><br />
    
    <h3>Stack Manipulation</h3>
    Rotate the top three elements: <span class="code">rot</span><br />
    Swap the top two elements: <span class="code">swap</span><br />        
    Duplicate: <span class="code">dup</span><br />
    Duplicate an element by position: <span class="code">dup#</span><br />
    Drop: <span class="code">drop</span><br />
    Drop an element by position: <span class="code">drop#</span><br />
    
    <h3>Blocks</h3>
    Execute a block: <span class="code">apply</span><br />
    Create a block out of the top two elements: <span class="code">block</span><br />
    Create a block out of the top X elements: <span class="code">block#</span><br />
    Concatenate the top two blocks into a single block: <span class="code">cat</span><br />
  </div>
  
  <div id="combinators">
    <h2>Combinators</h2>
    
    <h3>Fundamental Combinators</h3>
    <ul>
      <li>
        Swap the top element on stack.  This is a pre-defined core operation.<br />
        <span class="code">[B] [A] swap</span><span class="ex"> => [A] [B]</span><br />
      </li>
      <li>
        Duplicate the top element on stack.  This is a pre-defined core operation.<br />
        <span class="code">[A] dup</span><span class="ex"> => [A] [A]</span><br />
      </li>
      <li>
        Remove the top element on stack.  This is a pre-defined core operation.<br />
        <span class="code">[A] drop</span><span class="ex"> => NOTHING</span><br />
      </li>
      <li>
        Concatenate the top two blocks into a single block.  This is a pre-defined core operation.<br />
        <span class="code">[B] [A] cat</span><span class="ex"> => [B A]</span><br />
      </li>
      <li>
        Concatenate two blocks, leaving the first one, '[B]', as a block.<br />
        Definition: <span class="code">cons = swap 1 block# swap cat</span><br />
        Example: <span class="code">[B] [A] cons</span><span class="ex"> => [[B] A]</span><br />
      </li>      
      <li>
        Create a block out of the top element.<br />
        Definition: <span class="code">unit = 1 block#</span><br />
        Example: <span class="code">[A] unit</span><span class="ex"> => [[A]]</span><br />
      </li>
      <li>
        Execute a block.<br />
        Definition: <span class="code">i = apply</span><br />
        Example: <span class="code">[42] i</span><span class="ex"> => 42</span><br />
      </li>
      <li>
        Execute a block.<br />
        Definition: <span class="code">dip = swap 1 block# cat apply</span><br />
        Example 1: <span class="code">[B] [A] dip</span><span class="ex"> => A [B]</span><br />
        Example 2: <span class="code">[1 2 3] [4 5 6] dip</span><span class="ex"> => 4 5 6 [1 2 3]</span><br />
      </li>      
      
    </ul>
    
    <h3>Further Reading</h3>
    
    <ul>
      <li>
        <a class="external" target="_top" href="http://tunes.org/~iepos/joy.html">The Theory of Concatenative Combinators</a> by Brent Kerby<br />
        A comprehensive study of combinatory logic
      </li>
    </ul>
    
  </div>
  
  <div id="history">
    <h2>Version History</h2>
    
    <p>
      <a class="external" href="tests.html" target="_top">View the unit tests for the current version of Fika Shell</a>
    </p>
    
    <h3>Future Additions</h3>
    <ul>
      <li>Functional operations: map, filter, etc.</li>
      <li>
        Iterative operations like those described here:
        <a class="external" target="_top" href="http://tunes.org/~iepos/joy.html">The Theory of Concatenative Combinators</a>
      </li>
      <li>
        Lambdas like those described here:
        <a class="external" target="_top" href="http://tunes.org/~iepos/joy.html">The Theory of Concatenative Combinators</a>
      </li>
    </ul>
    
    <h3>0.1 (2008/12/14)</h3>
    <ul>
      <li>First released version.</li>
    </ul>
    
  </div>
  
  <div id="dev">
  	<h2>Development Notes</h2>
  	
  	<p>This works best in Chrome.</p>
  	
    <ul>
    	<li>
    		If running in from your local machine, you might have to start Chrome using this flag: --allow-file-access-from-files
    		<br />
    		So on Mac OS X, run this: <code>open /Applications/Google\ Chrome.app/ --args --allow-file-access-from-files</code>
    	</li>
    </ul>  
  </div>

</div>

</body>
</html>
